<!DOCTYPE html>
<html lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Boost build and test guide</title>
<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
</head>

<body>
<h1>Boost build and test guide</h1>

<p>This page is a guide to running the testing and timing programs for the
<a href="https://www.boost.org">Boost</a> class libraries as part of
GCC integration testing.</p>

<h2>Resource usage</h2>

<p>These instructions are for version 1.27.0, whose gzipped tar file is
3.8 MB.  The uncompressed distribution comprises some 16 MB of source files.
Building the library and tests adds between 80 and 140 MB of
object files and executables to this.</p>

<p>On a Pentium III laptop, building the Boost library takes 15 minutes
and building and running the regression tests takes an additional 5
minutes.</p>

<h2>Prepare</h2>

<p>To prepare for a build, perform the following:</p>
<ul>
<li>Unpack the file:
<ul>
<li><code>tar zxf boost_1_27_0.tar.gz</code>, or</li>
<li><code>gunzip -c boost_all.tar.gz | tar xf -</code></li>
</ul>
</li>
<li>Change directory to the repository thus created.
<ul>
<li><code>cd boost_1_27_0</code></li>
</ul>
</li>
<li>Define and  export environment variables:
    <ul>
    <li><code>PATH</code> should include the <code>bin</code> directory
        of the GCC installation under test.</li>
    <li><code>LD_LIBRARY_PATH</code> should include the <code>lib</code>
        directory of the GCC installation under test.</li>
    <li><code>BOOST_ROOT</code> should be the full pathname of the top
        directory of the boost distribution (the one to which we just
        changed).</li>
    </ul>
</li>
<li>Change a configuration check to recognize GCC versions later than
    3.1; in file <code>boost/config/compiler/gcc.hpp</code>, change
    <code>__GNUC_MINOR__ &gt; 1</code> to
    <code>__GNUC_MINOR__ &gt; 4</code>.</li>
<li>The test <code>libs/integer/integer_test.cpp</code> assumes that
    types <code>int</code> and <code>long</code> are the same size.
    If this isn't true for your target, modify the test file using
    <code>sed '/PRIVATE_FIT_TESTS/s/LONG_MAX/INT_MAX/'</code>.</li>
</ul>

<h2>Configure</h2>

<p>The Boost package gets information about how to compile and link
from the file <code>compiler.cfg</code>.  On a GNU/Linux system you
can replace the contents of that file with the following:</p>

<pre><code>linux
gcc-3.1
GCC 3.1
g++ -c -w -ftemplate-depth-30 -I%include %source
g++ -o boosttmp.exe -w -ftemplate-depth-30 -I%include %source -lrt
GNU&lt;br&gt;&lt;a href="https://gcc.gnu.org"&gt;GCC&lt;/a&gt;&lt;br&gt;3.1
</code></pre>

<p>To build the package with specific optimizations, add them to the
compile line in this file.</p>

<h2>Build</h2>

<p>To build the Boost class library, do:</p>

<pre><code>cd ${BOOST_ROOT}/tools/build/jam_src
make all
cd ${BOOST_ROOT}
tools/build/jam_src/jam0 \
    -sBOOST_ROOT=${BOOST_ROOT} -sTOOLS="gcc"
</code></pre>

<p>If you don't have Python installed, there will be build failures for
Python support.  The <code>wregex</code> support fails to build if glibc
is older than 2.2.4.  These failures do not prevent the build from
continuing.</p>

<h2>Test</h2>

<p>Build the Boost regression tests with:</p>

<pre><code>cd ${BOOST_ROOT}/status
g++ -I${BOOST_ROOT} -o regression regression.cpp
</code></pre>

<p>Run the tests with:</p>

<pre><code>cd ${BOOST_ROOT}/status
./regression
</code></pre>

<p>"Pass" or "Fail" appears at the end of the output for each test.
There should be no failures, although if your glibc is older than
2.2.4 then tests 
<code>libs/integer/integer_traits_test.cpp</code> and
<code>libs/regex/test/regress/wregex_test.cpp</code> will fail.</p>

<h2>Interoperability testing</h2>

<p>Boost can be used to test interoperability of two compilers by
building the Boost class library with one compiler and the regression
test with a different compiler.</p>

<h2>Time</h2>

<p>TBD</p>

<h2>Cleanup</h2>

<p>Cleanup (to prepare the directory for a fresh run, e.g.
with another version of the compiler), is done as follows:</p>

<pre><code>cd ${BOOST_ROOT}
rm -f ${BOOST_ROOT}/build/jam_src/jam0
rm -f ${BOOST_ROOT}/status/regression
find . -name \*.o -exec rm -f {} \;
</code></pre>

</body>
</html>
